NOTE: This program is _not_ public domain but shareware. This means you have a license to posses and use this program for 45 days before you either must send me $5 for my efforts or destroy the program and all copies of it (or better yet, give it to a friend.
You are actively encouraged to give copies of this program to _all_ of your friends and upload it to all BBS systems you can get it on. Never, under any circumstances, distribute the program file without the documentation file.
For you users who have already sent in their registration fee of $5 then they can automatically assume ownership of all new versions without paying another fee.
So if you want to receive all versions of this great program, please register soon. Due to the time this takes up I may raise the registration price sometime in the near future so I suggest you hurry.
This program is updated regularly so you constantly get new updates and features. Sign up now.
New features are in the works on version 1.2 which will allow much improved disassembly and better dump to printer command. Online help is being contemplated along with configuration with machine and find commands. The next version will definitly have Apple ][ and ][+ compatability.
Send checks and money orders to:
Dion Hinchcliffe
6121 Empire Circle
Las Vegas, NV 89107
==> Dion Hinchcliffe - 8/30/85
Have you ever wanted to access ProDOS volumes directly, or change information without having to load it in? If so, then this is the program for you. The ProDOS Block Editor will let you easily alter the information on any ProDOS volume including hard drives and RAM disks.
This program gives you some quite powerful features to control the information on a ProDOS volume. Care must be exercised when using this program or file integrity can be damaged. Among the more powerful of these features is the ability to place the buffer anywhere in memory you wish except for places marked in the Global Bit Map ($BF58-$BF6F) or above $8300. Functions are provided to easily alter memory by either entering information as hexadecimal or by typing an ASCII character. A feature is provided to disassemble the information anywhere in the current buffer and if you posses a printer you can dump memory to it from within the program.
Program Setup
Since ProDOS blocks are 512 bytes in length I decided to split each block read into memory into four 128 byte sub-buffers, this was done so the user could swiftly toggle between the four sub-buffers in memory.
A DOS 3.3 sector editor can be used to access ProDOS disks, but you cannot determine which half block you are viewing. In addition, no DOS 3.3 sectors editors will function under ProDOS.
On a standard floppy disk there are 118 hex (280 decimal) blocks, and much more on a hard drive. Entering block numbers to access is done in a hexadecimal format since information on storage devices is kept in hex. Buffer areas must be placed starting at the beginning of a new memory page, i.e. the low byte of the buffer address must be zero. When viewing one of the sub-buffers the data is kept in 16 lines of eight bytes each. Each line will start with the memory address that those eight bytes begin on. The right-hand section of the screen shows the ASCII representation of the preceeding eight bytes, all character values including control characters, inverse, and flashing text are converted to normal format.
Commands
The ProDOS Block Editor is quite easy to use. All commands are one key and should be easy to remember. A list of the most common commands is kept at the top of the screen. The following is a list of commands and a short explanation of each:
--> (Right arrow): This command will switch you to the next sub-buffer in memory. If you are already at the top of the buffer then you will be prevented from going further.
<-- (Left arrow): Move down to the next sub-buffer. Again, if you are already at the bottom of the buffer then you will not be able to continue.
+: This key lets you increment the current block number by one in order to save you time instead of typing in the block number manually. The '=' key can be used for the same function so you don't have to press the <Shift> key down at the same time.
-: This functions allows you to decrement one from the current block number. And generally performs the same function as the '+' except in reverse.
I,J,K,M: These keys will allow you to move the cursor around the screen. The cursor is represented by the inverse of whatever byte it is placed over, if you go over the left- or right-hand margin the cursor will wrap over to the next line without stopping.
R: Read block from current memory storage device. This command reads a ProDOS block of 512 bytes from the memory storage device connected in the slot and drive specified, this includes the ProDOS /RAM disk and hard drives. The number of the block read in is specified with the 'B' option.
W: This is similiar to Read option except it writes information from the current buffer position to the selected block number in the memory storage device. Be very careful when you write to the disk, once data has been written it cannot be undone.
D: Dump 256 bytes of the buffer starting at the cursor position to the printer (dot-matrix or daisy-wheel). The printer card must be in slot one to perform this function, the system may lock if you don't have a printer card so it is strongly suggested you ignore this command if you are without a serial or parallel card in Slot #1.
B: Select new location for data buffer. Executing this command will allow you to type the new page number to position the buffer on. Pressing <ESC> while typing in the new number will restore the old value and exit you from the function. Warning: You can place the buffer on places marked in the Global Bit-Map but you cannot read data into these places; you may write from them, however.
N: This function allows you to specify the new block number you wish to read from or write to. The number must be a hexadecimal numeral, pressed <ESC> while typing in the new number will restore the old value and exit you from the function.
Q: This command will allow you to quit the program and return to BASIC.
A: This will allow you to replace the byte under the cursor with the value of the ASCII key pressed after the 'A' selection is made.
<CR>: Pressing Return will let you replace the byte under the cursor with a new hexadecimal value. While typing in the new value you can press <ESC> to abort the function and restore the old value.
L: You can disassemble the hex code starting from the current cursor position by executing this function. Twenty instructions are disassembled. There will be a provision in the next version of PBE to dump to the printer.
S,1,2: You can select the slot by pressing 'S' until the desired slot number appears. Pressing '1' or '2' will allow you to switch between drive one or two. You should have drive two selected if you are using a /RAM disk or hard drive.
More complete instructions of how to use the ProDOS Block Editor follow, which completely detail all aspects of this program.
Using the Program
When you start out the current buffer area is set to $5000 and the block number is defaulted to zero. Commonly used commands are listed at the top of the screen. When you select a new area for the data buffer no areas above $8300 will be accepted lest you damage the program or the ProDOS operating system. If you own a standard Disk II floppy drive blocks are numbered from $0000 to $0118, any number greater than $0118 will cause an error $28 during a read or write. Block numbers on hard drives will vary with number of megabytes. Using a standard extended text card gives you $80 (128 decimal) blocks available for access.
The cursor, represented by an inverse byte on the screen within the memory field, is used a pointer in this program. It allows you to look where you would like. Where it points you can alter, look or replace memory. You can control it by using the I-J-K-M keys to move it within the memory field. You have two features available to alter the byte under the cursor, you can press <CR> and directly type the hexadecimal value or type 'A' and press any ASCII character and have the value stored in the buffer. If, while in the middle of entering a byte, you decide to abort, you can hit <ESC> to quit entering the old value.
The 'B' function will allow you to relocate the buffer in order to store the information elsewhere. Information cannot be stored above $8300 lest you damage the program or the ProDOS operating system. You can place information over the zero page, stack page or text page ($0000-$0800) but this should be avoided at all costs. You can only set the page number of the buffer area ($00-$83) because all storage must begin on a page boundary.
You can increment and decrement the current block number by one using the '+' and '-' commands respectively. This is a lot faster than the 'N' command if you just want to set a block number one or two values higher. (By the way, you can use the '=' instead of '+' so you don't have to press down the <Shift> key).
You can print the buffer on a standard parallel or serial printer starting at the current cursor position using the 'D' function. Information is printed for 256 characters, a field of 32 lines of 8 bytes each is constructed. An ASCII representation of each byte is kept at the right of the memory field.
R) eading and W) riting information is done using the ProDOS Machine
Language Interface at $BF00. Data is read into memory starting at the bottom of the buffer, from the specified block number on the current memory storage device. The information is written into memory for 512 consecutive bytes (one block). Data is written to the current memory device in a similiar fashion; from the current buffer to the predetermined block on the current memory storage device. Warning: If you write improper information on a ProDOS volume, file integrity can be damaged permanently so be very careful.
Using the 'N' option allows you to specify which block you would like to reference next. Hexadecimal format must be used to enter the block number. The numbers $0000-$FFFF can be used. If you are using a standard Disk II drive or the new Duo Drive, the block numbers that can be used are between $0000-$0117. The /RAM disk in an extended text card can access block numbers $0000-$007F, and a hard drive can access many more blocks. A 32-megabyte drive can access blocks $0000-$FFFF exactly. Pressing <ESC>ape during the input of the new block number will abort the input and restore the old value. Attempting to read block numbers higher than those permitted by the currently used memory storage device will cause an error.
Entering information in the buffer can be done with either one of two methods. The first uses direct hexadecimal input. You press the RETURN key and enter a two-byte hexadecimal numeral between $00-$FF. The result of the input will be placed in the memory location represented by the current cursor position. Pressing <ESC> during the input will exit you from this function and put the old value back. The other way of entering new data is pressing 'A' and then any ASCII character value. The hexadecimal value of that keypress will be stored at the current cursor position.
You can disassemble 20 machine language instructions starting at the current cursor position using the 'L' command. Memory references may be off due the location that the data is stored in; however, relative references are kept intact. Pressing any key will take you out of the disassembly and back into the block editor.
Slots and drives can easily be selected using the 'S','1', and '2' commands. Pressing 'S' will select the next highest slot unless you are already at the highest. After slot 7 you will be taken down to slot 3, the lowest slot accessible by the block editor. The drives can be selected by pressing '1' or '2'. The current slot and drive values are kept on the status line on the bottom of the screen. Select slot three if you wish to access the extended text card /RAM disk. Drive one should be set if you are using the /RAM disk or a hard drive.
You can exit the program using the 'Q' option. This will drop you down into BASIC. If you had a BASIC program in memory and you did not move the buffer over it, it should be intact.
Error Messages
A few errors can be generated using the ProDOS Block Editor; they can only be caused during disk access. These can be caused for various reasons. You can find a list of the errors, their causes, and solutions in the ProDOS Technical Refence Manual.
Uses of the ProDOS Block Editor
If you have ever had to use a DOS 3.3 sector editor you know how this program can be used and the benefits it gives you. Even if you have not, this program is still a valuable addition to your programming library. Uses range from altering ProDOS itself to changing the boot-up header, altering programs directly, undeleting files, or repairing damaged file information. Any byte of data stored on a ProDOS volume can be altered and stored permanently on any memory storage device. The uses are virtually endless.
About the Program
The ProDOS Block Editor was written in a modular format. The beginning of the program is entirely subroutines, the program that calls these subroutines is located at the end of the code. The command processor jumps to the routines as necessary to execute the requested commands. As many of the subroutines are called by other subroutines, the modular format was adopted to prevent what is known as "Spaghetti Code". Even though the code is fairly complex the program is easy to trace and modify since all functions are contained within subroutines.
The command parser was designed so that extra commands may be easily added. All you do is alter the number of the commands and then add the letter of the command at the end of the command list. Then store the lo-byte, hi-byte address of the command at the very end of the command addresses. A catalog command could be added this way, and it would be a very easy addition to the program.
If you dislike the lettering of the commands they can be easily changed by altering the ASCII list of commands inside the command parser. After you reassemble the program (or alter it from the monitor) you can use the new command keys instead of the old ones.
The program is fully commented and should be a benefit to people
interested in using ProDOS with their machine language programs.
